…chy, UpstreamPin, helpers

- Replace FORBIDDEN_VERIFICATION_STATUSES blocklist with
  ALLOWED_VERIFICATION_STATUSES allowlist: new upstream statuses now
  fail closed instead of silently passing the gate.
- Add UpstreamError base class; derive all three error classes from it
  so callers can catch any module error with a single type. Raise
  UpstreamError (not ValueError/RuntimeError) from _normalize_remote_url
  and _run_git.
- Add UpstreamPin frozen dataclass; upstream_pin_from_checkout now
  returns UpstreamPin(repo, revision) instead of a plain tuple[str, str].
- Split _run_git into _run_git_raw (always returns CompletedProcess) and
  _run_git (raises on non-zero). upstream_pin_from_checkout now uses
  _run_git_raw for the symbolic-ref detached-HEAD check — all subprocess
  calls go through the same internal layer.
- Implement is_eligible independently with short-circuit boolean
  evaluation; it no longer delegates to explain_ineligible, eliminating
  the list allocation on every filter-loop call.
- Add docstrings to all dataclass classes documenting which fields are
  required vs. nullable and what values are expected.
- load_entries now raises UpstreamError immediately when path does not
  exist, rather than letting FileNotFoundError propagate unwrapped.
- Tests: add test_normalize_remote_url parametrize that tests the regex
  directly (no subprocess overhead); add test_load_entries_raises_on_missing_file,
  test_load_error_is_upstream_error, test_checkout_errors_are_upstream_errors,
  and test_is_eligible_and_explain_ineligible_agree; fix
  test_pin_normalizes_remote_url to use tmp_path / 'upstream' (each
  parametrize case gets its own tmp_path — hash() dir names were
  unnecessary and non-deterministic); rename test_pin_returns_repo_and_revision
  to test_pin_returns_upstream_pin and assert against UpstreamPin.
- Update docs/upstream_integration.md: UpstreamPin return type,
  allowlist language for verification_status.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>